home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 2003 August / MW 8 2003 CD1.iso / Inside Macworld / Product News / gimp-1.2.4.sit / gimp-1.2.4 / devel-docs / libgimp / sgml / gimpmatrix.sgml < prev    next >
Encoding:
Text File  |  2003-05-20  |  17.9 KB  |  418 lines
  1. <refentry id="libgimp-gimpmatrix" revision="19 Jan 2001">
  2. <refmeta>
  3. <refentrytitle>gimpmatrix</refentrytitle>
  4. <manvolnum>3</manvolnum>
  5. <refmiscinfo>LIBGIMP Library</refmiscinfo>
  6. </refmeta>
  7.  
  8. <refnamediv>
  9. <refname>gimpmatrix</refname><refpurpose>Utilities to set up and manipulate 3x3 transformation matrices.</refpurpose>
  10. </refnamediv>
  11.  
  12. <refsynopsisdiv><title>Synopsis</title>
  13. <synopsis>
  14.  
  15.  
  16.  
  17. typedef     <link linkend="GimpMatrix3[3][3]">GimpMatrix3[3][3]</link>;
  18. typedef     <link linkend="GimpMatrix4[4][4]">GimpMatrix4[4][4]</link>;
  19. void        <link linkend="gimp-matrix3-transform-point">gimp_matrix3_transform_point</link>    (<link linkend="GimpMatrix3">GimpMatrix3</link> matrix,
  20.                                              <link linkend="gdouble">gdouble</link> x,
  21.                                              <link linkend="gdouble">gdouble</link> y,
  22.                                              <link linkend="gdouble">gdouble</link> *newx,
  23.                                              <link linkend="gdouble">gdouble</link> *newy);
  24. void        <link linkend="gimp-matrix3-mult">gimp_matrix3_mult</link>               (<link linkend="GimpMatrix3">GimpMatrix3</link> matrix1,
  25.                                              <link linkend="GimpMatrix3">GimpMatrix3</link> matrix2);
  26. void        <link linkend="gimp-matrix3-identity">gimp_matrix3_identity</link>           (<link linkend="GimpMatrix3">GimpMatrix3</link> matrix);
  27. void        <link linkend="gimp-matrix3-translate">gimp_matrix3_translate</link>          (<link linkend="GimpMatrix3">GimpMatrix3</link> matrix,
  28.                                              <link linkend="gdouble">gdouble</link> x,
  29.                                              <link linkend="gdouble">gdouble</link> y);
  30. void        <link linkend="gimp-matrix3-scale">gimp_matrix3_scale</link>              (<link linkend="GimpMatrix3">GimpMatrix3</link> matrix,
  31.                                              <link linkend="gdouble">gdouble</link> x,
  32.                                              <link linkend="gdouble">gdouble</link> y);
  33. void        <link linkend="gimp-matrix3-rotate">gimp_matrix3_rotate</link>             (<link linkend="GimpMatrix3">GimpMatrix3</link> matrix,
  34.                                              <link linkend="gdouble">gdouble</link> theta);
  35. void        <link linkend="gimp-matrix3-xshear">gimp_matrix3_xshear</link>             (<link linkend="GimpMatrix3">GimpMatrix3</link> matrix,
  36.                                              <link linkend="gdouble">gdouble</link> amount);
  37. void        <link linkend="gimp-matrix3-yshear">gimp_matrix3_yshear</link>             (<link linkend="GimpMatrix3">GimpMatrix3</link> matrix,
  38.                                              <link linkend="gdouble">gdouble</link> amount);
  39. <link linkend="gdouble">gdouble</link>     <link linkend="gimp-matrix3-determinant">gimp_matrix3_determinant</link>        (<link linkend="GimpMatrix3">GimpMatrix3</link> matrix);
  40. void        <link linkend="gimp-matrix3-invert">gimp_matrix3_invert</link>             (<link linkend="GimpMatrix3">GimpMatrix3</link> matrix,
  41.                                              <link linkend="GimpMatrix3">GimpMatrix3</link> matrix_inv);
  42. void        <link linkend="gimp-matrix3-duplicate">gimp_matrix3_duplicate</link>          (<link linkend="GimpMatrix3">GimpMatrix3</link> src,
  43.                                              <link linkend="GimpMatrix3">GimpMatrix3</link> target);
  44. <link linkend="gboolean">gboolean</link>    <link linkend="gimp-matrix3-is-diagonal">gimp_matrix3_is_diagonal</link>        (<link linkend="GimpMatrix3">GimpMatrix3</link> matrix);
  45. <link linkend="gboolean">gboolean</link>    <link linkend="gimp-matrix3-is-identity">gimp_matrix3_is_identity</link>        (<link linkend="GimpMatrix3">GimpMatrix3</link> matrix);
  46. <link linkend="gboolean">gboolean</link>    <link linkend="gimp-matrix3-is-simple">gimp_matrix3_is_simple</link>          (<link linkend="GimpMatrix3">GimpMatrix3</link> matrix);
  47. void        <link linkend="gimp-matrix4-to-deg">gimp_matrix4_to_deg</link>             (<link linkend="GimpMatrix4">GimpMatrix4</link> matrix,
  48.                                              <link linkend="gdouble">gdouble</link> *a,
  49.                                              <link linkend="gdouble">gdouble</link> *b,
  50.                                              <link linkend="gdouble">gdouble</link> *c);
  51. </synopsis>
  52. </refsynopsisdiv>
  53.  
  54.  
  55.  
  56.  
  57.  
  58. <refsect1>
  59. <title>Description</title>
  60. <para>
  61. When doing image manipulation you will often need 3x3 transformation
  62. matrices that define translation, rotation, scaling, shearing and 
  63. arbitrary perspective transformations using a 3x3 matrix. Here you'll 
  64. find a set of utility functions to set up those matrices and to perform 
  65. basic matrix manipulations and tests.
  66. </para>
  67. </refsect1>
  68.  
  69. <refsect1>
  70. <title>Details</title>
  71. <refsect2>
  72. <title><anchor id="GimpMatrix3[3][3]">GimpMatrix3[3][3]</title>
  73. <programlisting>typedef gdouble GimpMatrix3[3][3];
  74. </programlisting>
  75. <para>
  76.  
  77. </para></refsect2>
  78. <refsect2>
  79. <title><anchor id="GimpMatrix4[4][4]">GimpMatrix4[4][4]</title>
  80. <programlisting>typedef gdouble GimpMatrix4[4][4];
  81. </programlisting>
  82. <para>
  83.  
  84. </para></refsect2>
  85. <refsect2>
  86. <title><anchor id="gimp-matrix3-transform-point">gimp_matrix3_transform_point ()</title>
  87. <programlisting>void        gimp_matrix3_transform_point    (<link linkend="GimpMatrix3">GimpMatrix3</link> matrix,
  88.                                              <link linkend="gdouble">gdouble</link> x,
  89.                                              <link linkend="gdouble">gdouble</link> y,
  90.                                              <link linkend="gdouble">gdouble</link> *newx,
  91.                                              <link linkend="gdouble">gdouble</link> *newy);</programlisting>
  92. <para>
  93. Transforms a point in 2D as specified by the transformation matrix.</para>
  94. <para>
  95.  
  96. </para><informaltable pgwide=1 frame="none" role="params">
  97. <tgroup cols="2">
  98. <colspec colwidth="2*">
  99. <colspec colwidth="8*">
  100. <tbody>
  101. <row><entry align="right"><parameter>matrix</parameter> :</entry>
  102. <entry> The transformation matrix.
  103. </entry></row>
  104. <row><entry align="right"><parameter>x</parameter> :</entry>
  105. <entry> The source X coordinate.
  106. </entry></row>
  107. <row><entry align="right"><parameter>y</parameter> :</entry>
  108. <entry> The source Y coordinate.
  109. </entry></row>
  110. <row><entry align="right"><parameter>newx</parameter> :</entry>
  111. <entry> The transformed X coordinate.
  112. </entry></row>
  113. <row><entry align="right"><parameter>newy</parameter> :</entry>
  114. <entry> The transformed Y coordinate.
  115. </entry></row>
  116. </tbody></tgroup></informaltable></refsect2>
  117. <refsect2>
  118. <title><anchor id="gimp-matrix3-mult">gimp_matrix3_mult ()</title>
  119. <programlisting>void        gimp_matrix3_mult               (<link linkend="GimpMatrix3">GimpMatrix3</link> matrix1,
  120.                                              <link linkend="GimpMatrix3">GimpMatrix3</link> matrix2);</programlisting>
  121. <para>
  122. Multiplies two matrices and puts the result into the second one.</para>
  123. <para>
  124.  
  125. </para><informaltable pgwide=1 frame="none" role="params">
  126. <tgroup cols="2">
  127. <colspec colwidth="2*">
  128. <colspec colwidth="8*">
  129. <tbody>
  130. <row><entry align="right"><parameter>matrix1</parameter> :</entry>
  131. <entry> The first input matrix.
  132. </entry></row>
  133. <row><entry align="right"><parameter>matrix2</parameter> :</entry>
  134. <entry> The second input matrix which will be oeverwritten ba the result.
  135. </entry></row>
  136. </tbody></tgroup></informaltable></refsect2>
  137. <refsect2>
  138. <title><anchor id="gimp-matrix3-identity">gimp_matrix3_identity ()</title>
  139. <programlisting>void        gimp_matrix3_identity           (<link linkend="GimpMatrix3">GimpMatrix3</link> matrix);</programlisting>
  140. <para>
  141. Sets the matrix to the identity matrix.</para>
  142. <para>
  143.  
  144. </para><informaltable pgwide=1 frame="none" role="params">
  145. <tgroup cols="2">
  146. <colspec colwidth="2*">
  147. <colspec colwidth="8*">
  148. <tbody>
  149. <row><entry align="right"><parameter>matrix</parameter> :</entry>
  150. <entry> A matrix.
  151. </entry></row>
  152. </tbody></tgroup></informaltable></refsect2>
  153. <refsect2>
  154. <title><anchor id="gimp-matrix3-translate">gimp_matrix3_translate ()</title>
  155. <programlisting>void        gimp_matrix3_translate          (<link linkend="GimpMatrix3">GimpMatrix3</link> matrix,
  156.                                              <link linkend="gdouble">gdouble</link> x,
  157.                                              <link linkend="gdouble">gdouble</link> y);</programlisting>
  158. <para>
  159. Translates the matrix by x and y.</para>
  160. <para>
  161.  
  162. </para><informaltable pgwide=1 frame="none" role="params">
  163. <tgroup cols="2">
  164. <colspec colwidth="2*">
  165. <colspec colwidth="8*">
  166. <tbody>
  167. <row><entry align="right"><parameter>matrix</parameter> :</entry>
  168. <entry> The matrix that is to be translated.
  169. </entry></row>
  170. <row><entry align="right"><parameter>x</parameter> :</entry>
  171. <entry> Translation in X direction.
  172. </entry></row>
  173. <row><entry align="right"><parameter>y</parameter> :</entry>
  174. <entry> Translation in Y direction.
  175. </entry></row>
  176. </tbody></tgroup></informaltable></refsect2>
  177. <refsect2>
  178. <title><anchor id="gimp-matrix3-scale">gimp_matrix3_scale ()</title>
  179. <programlisting>void        gimp_matrix3_scale              (<link linkend="GimpMatrix3">GimpMatrix3</link> matrix,
  180.                                              <link linkend="gdouble">gdouble</link> x,
  181.                                              <link linkend="gdouble">gdouble</link> y);</programlisting>
  182. <para>
  183. Scales the matrix by x and y</para>
  184. <para>
  185.  
  186. </para><informaltable pgwide=1 frame="none" role="params">
  187. <tgroup cols="2">
  188. <colspec colwidth="2*">
  189. <colspec colwidth="8*">
  190. <tbody>
  191. <row><entry align="right"><parameter>matrix</parameter> :</entry>
  192. <entry> The matrix that is to be scaled.
  193. </entry></row>
  194. <row><entry align="right"><parameter>x</parameter> :</entry>
  195. <entry> X scale factor.
  196. </entry></row>
  197. <row><entry align="right"><parameter>y</parameter> :</entry>
  198. <entry> Y scale factor.
  199. </entry></row>
  200. </tbody></tgroup></informaltable></refsect2>
  201. <refsect2>
  202. <title><anchor id="gimp-matrix3-rotate">gimp_matrix3_rotate ()</title>
  203. <programlisting>void        gimp_matrix3_rotate             (<link linkend="GimpMatrix3">GimpMatrix3</link> matrix,
  204.                                              <link linkend="gdouble">gdouble</link> theta);</programlisting>
  205. <para>
  206. Rotates the matrix by theta degrees.</para>
  207. <para>
  208.  
  209. </para><informaltable pgwide=1 frame="none" role="params">
  210. <tgroup cols="2">
  211. <colspec colwidth="2*">
  212. <colspec colwidth="8*">
  213. <tbody>
  214. <row><entry align="right"><parameter>matrix</parameter> :</entry>
  215. <entry> The matrix that is to be rotated.
  216. </entry></row>
  217. <row><entry align="right"><parameter>theta</parameter> :</entry>
  218. <entry> The angle of rotation (in radians).
  219. </entry></row>
  220. </tbody></tgroup></informaltable></refsect2>
  221. <refsect2>
  222. <title><anchor id="gimp-matrix3-xshear">gimp_matrix3_xshear ()</title>
  223. <programlisting>void        gimp_matrix3_xshear             (<link linkend="GimpMatrix3">GimpMatrix3</link> matrix,
  224.                                              <link linkend="gdouble">gdouble</link> amount);</programlisting>
  225. <para>
  226. Shears the matrix in the X direction.</para>
  227. <para>
  228.  
  229. </para><informaltable pgwide=1 frame="none" role="params">
  230. <tgroup cols="2">
  231. <colspec colwidth="2*">
  232. <colspec colwidth="8*">
  233. <tbody>
  234. <row><entry align="right"><parameter>matrix</parameter> :</entry>
  235. <entry> The matrix that is to be sheared.
  236. </entry></row>
  237. <row><entry align="right"><parameter>amount</parameter> :</entry>
  238. <entry> X shear amount.
  239. </entry></row>
  240. </tbody></tgroup></informaltable></refsect2>
  241. <refsect2>
  242. <title><anchor id="gimp-matrix3-yshear">gimp_matrix3_yshear ()</title>
  243. <programlisting>void        gimp_matrix3_yshear             (<link linkend="GimpMatrix3">GimpMatrix3</link> matrix,
  244.                                              <link linkend="gdouble">gdouble</link> amount);</programlisting>
  245. <para>
  246. Shears the matrix in the Y direction.</para>
  247. <para>
  248.  
  249. </para><informaltable pgwide=1 frame="none" role="params">
  250. <tgroup cols="2">
  251. <colspec colwidth="2*">
  252. <colspec colwidth="8*">
  253. <tbody>
  254. <row><entry align="right"><parameter>matrix</parameter> :</entry>
  255. <entry> The matrix that is to be sheared.
  256. </entry></row>
  257. <row><entry align="right"><parameter>amount</parameter> :</entry>
  258. <entry> Y shear amount.
  259. </entry></row>
  260. </tbody></tgroup></informaltable></refsect2>
  261. <refsect2>
  262. <title><anchor id="gimp-matrix3-determinant">gimp_matrix3_determinant ()</title>
  263. <programlisting><link linkend="gdouble">gdouble</link>     gimp_matrix3_determinant        (<link linkend="GimpMatrix3">GimpMatrix3</link> matrix);</programlisting>
  264. <para>
  265. Calculates the determinant of the given matrix.</para>
  266. <para>
  267.  
  268. </para><informaltable pgwide=1 frame="none" role="params">
  269. <tgroup cols="2">
  270. <colspec colwidth="2*">
  271. <colspec colwidth="8*">
  272. <tbody>
  273. <row><entry align="right"><parameter>matrix</parameter> :</entry>
  274. <entry> The input matrix. 
  275. </entry></row>
  276. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The determinant.
  277. </entry></row>
  278. </tbody></tgroup></informaltable></refsect2>
  279. <refsect2>
  280. <title><anchor id="gimp-matrix3-invert">gimp_matrix3_invert ()</title>
  281. <programlisting>void        gimp_matrix3_invert             (<link linkend="GimpMatrix3">GimpMatrix3</link> matrix,
  282.                                              <link linkend="GimpMatrix3">GimpMatrix3</link> matrix_inv);</programlisting>
  283. <para>
  284. Inverts the given matrix.</para>
  285. <para>
  286.  
  287. </para><informaltable pgwide=1 frame="none" role="params">
  288. <tgroup cols="2">
  289. <colspec colwidth="2*">
  290. <colspec colwidth="8*">
  291. <tbody>
  292. <row><entry align="right"><parameter>matrix</parameter> :</entry>
  293. <entry> The matrix that is to be inverted.
  294. </entry></row>
  295. <row><entry align="right"><parameter>matrix_inv</parameter> :</entry>
  296. <entry> A matrix the inverted matrix should be written into. 
  297. </entry></row>
  298. </tbody></tgroup></informaltable></refsect2>
  299. <refsect2>
  300. <title><anchor id="gimp-matrix3-duplicate">gimp_matrix3_duplicate ()</title>
  301. <programlisting>void        gimp_matrix3_duplicate          (<link linkend="GimpMatrix3">GimpMatrix3</link> src,
  302.                                              <link linkend="GimpMatrix3">GimpMatrix3</link> target);</programlisting>
  303. <para>
  304. Copies the source matrix to the destination matrix.</para>
  305. <para>
  306.  
  307. </para><informaltable pgwide=1 frame="none" role="params">
  308. <tgroup cols="2">
  309. <colspec colwidth="2*">
  310. <colspec colwidth="8*">
  311. <tbody>
  312. <row><entry align="right"><parameter>src</parameter> :</entry>
  313. <entry> The source matrix.
  314. </entry></row>
  315. <row><entry align="right"><parameter>target</parameter> :</entry>
  316. <entry> The destination matrix. 
  317. </entry></row>
  318. </tbody></tgroup></informaltable></refsect2>
  319. <refsect2>
  320. <title><anchor id="gimp-matrix3-is-diagonal">gimp_matrix3_is_diagonal ()</title>
  321. <programlisting><link linkend="gboolean">gboolean</link>    gimp_matrix3_is_diagonal        (<link linkend="GimpMatrix3">GimpMatrix3</link> matrix);</programlisting>
  322. <para>
  323. Checks if the given matrix is diagonal.</para>
  324. <para>
  325.  
  326. </para><informaltable pgwide=1 frame="none" role="params">
  327. <tgroup cols="2">
  328. <colspec colwidth="2*">
  329. <colspec colwidth="8*">
  330. <tbody>
  331. <row><entry align="right"><parameter>matrix</parameter> :</entry>
  332. <entry> The matrix that is to be tested.
  333. </entry></row>
  334. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> TRUE if the matrix is diagonal.
  335. </entry></row>
  336. </tbody></tgroup></informaltable></refsect2>
  337. <refsect2>
  338. <title><anchor id="gimp-matrix3-is-identity">gimp_matrix3_is_identity ()</title>
  339. <programlisting><link linkend="gboolean">gboolean</link>    gimp_matrix3_is_identity        (<link linkend="GimpMatrix3">GimpMatrix3</link> matrix);</programlisting>
  340. <para>
  341. Checks if the given matrix is the identity matrix.</para>
  342. <para>
  343.  
  344. </para><informaltable pgwide=1 frame="none" role="params">
  345. <tgroup cols="2">
  346. <colspec colwidth="2*">
  347. <colspec colwidth="8*">
  348. <tbody>
  349. <row><entry align="right"><parameter>matrix</parameter> :</entry>
  350. <entry> The matrix that is to be tested.
  351. </entry></row>
  352. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> TRUE if the matrix is the identity matrix.
  353. </entry></row>
  354. </tbody></tgroup></informaltable></refsect2>
  355. <refsect2>
  356. <title><anchor id="gimp-matrix3-is-simple">gimp_matrix3_is_simple ()</title>
  357. <programlisting><link linkend="gboolean">gboolean</link>    gimp_matrix3_is_simple          (<link linkend="GimpMatrix3">GimpMatrix3</link> matrix);</programlisting>
  358. <para>
  359. Checks if we'll need to interpolate when applying this matrix as
  360. a transformation.</para>
  361. <para>
  362.  
  363. </para><informaltable pgwide=1 frame="none" role="params">
  364. <tgroup cols="2">
  365. <colspec colwidth="2*">
  366. <colspec colwidth="8*">
  367. <tbody>
  368. <row><entry align="right"><parameter>matrix</parameter> :</entry>
  369. <entry> The matrix that is to be tested.
  370. </entry></row>
  371. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> TRUE if all entries of the upper left 2x2 matrix are either 
  372. 0 or 1
  373. </entry></row>
  374. </tbody></tgroup></informaltable></refsect2>
  375. <refsect2>
  376. <title><anchor id="gimp-matrix4-to-deg">gimp_matrix4_to_deg ()</title>
  377. <programlisting>void        gimp_matrix4_to_deg             (<link linkend="GimpMatrix4">GimpMatrix4</link> matrix,
  378.                                              <link linkend="gdouble">gdouble</link> *a,
  379.                                              <link linkend="gdouble">gdouble</link> *b,
  380.                                              <link linkend="gdouble">gdouble</link> *c);</programlisting>
  381. <para>
  382.  
  383. </para><informaltable pgwide=1 frame="none" role="params">
  384. <tgroup cols="2">
  385. <colspec colwidth="2*">
  386. <colspec colwidth="8*">
  387. <tbody>
  388. <row><entry align="right"><parameter>matrix</parameter> :</entry>
  389. <entry></entry></row>
  390. <row><entry align="right"><parameter>a</parameter> :</entry>
  391. <entry></entry></row>
  392. <row><entry align="right"><parameter>b</parameter> :</entry>
  393. <entry></entry></row>
  394. <row><entry align="right"><parameter>c</parameter> :</entry>
  395. <entry>
  396.  
  397. </entry></row>
  398. </tbody></tgroup></informaltable></refsect2>
  399.  
  400. </refsect1>
  401.  
  402.  
  403.  
  404. <refsect1>
  405. <title>See Also</title>
  406. <para>
  407. <link linkend="GimpVector2">GimpVector2</link>
  408. </para>
  409. <para>
  410. <link linkend="GimpVector3">GimpVector3</link>
  411. </para>
  412. <para>
  413. <link linkend="GimpVector4">GimpVector4</link>
  414. </para>
  415. </refsect1>
  416.  
  417. </refentry>
  418.